<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/xhtml;charset=UTF-8"/>
<meta http-equiv="X-UA-Compatible" content="IE=9"/>
<meta name="generator" content="Doxygen 1.8.9.1"/>
<title>OCILIB (C and C++ Driver for Oracle): Character sets</title>
<link href="tabs.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="jquery.js"></script>
<script type="text/javascript" src="dynsections.js"></script>
<link href="navtree.css" rel="stylesheet" type="text/css"/>
<script type="text/javascript" src="resize.js"></script>
<script type="text/javascript" src="navtreedata.js"></script>
<script type="text/javascript" src="navtree.js"></script>
<script type="text/javascript">
  $(document).ready(initResizable);
  $(window).load(resizeHeight);
</script>
<link href="doxygen.css" rel="stylesheet" type="text/css" />
</head>
<body>
<div id="top"><!-- do not remove this div, it is closed by doxygen! -->
<div id="titlearea">
<table cellspacing="0" cellpadding="0">
 <tbody>
 <tr style="height: 56px;">
  <td style="padding-left: 0.5em;">
   <div id="projectname">OCILIB (C and C++ Driver for Oracle)
   &#160;<span id="projectnumber">4.2.1</span>
   </div>
  </td>
 </tr>
 </tbody>
</table>
</div>
<!-- end header part -->
<!-- Generated by Doxygen 1.8.9.1 -->
  <div id="navrow1" class="tabs">
    <ul class="tablist">
      <li><a href="index.html"><span>About</span></a></li>
      <li><a href="modules.html"><span>Documentation</span></a></li>
      <li><a href="namespaces.html"><span>Namespaces</span></a></li>
      <li><a href="annotated.html"><span>Classes</span></a></li>
      <li><a href="files.html"><span>Files</span></a></li>
    </ul>
  </div>
</div><!-- top -->
<div id="side-nav" class="ui-resizable side-nav-resizable">
  <div id="nav-tree">
    <div id="nav-tree-contents">
      <div id="nav-sync" class="sync"></div>
    </div>
  </div>
  <div id="splitbar" style="-moz-user-select:none;" 
       class="ui-resizable-handle">
  </div>
</div>
<script type="text/javascript">
$(document).ready(function(){initNavTree('group___ocilib_c_api_supported_charsets.html','');});
</script>
<div id="doc-content">
<div class="header">
  <div class="headertitle">
<div class="title">Character sets<div class="ingroups"><a class="el" href="group___ocilib_c_api.html">C API</a></div></div>  </div>
</div><!--header-->
<div class="contents">
<a name="details" id="details"></a><h2 class="groupheader">Detailed Description</h2>
<p>OCILIB supports both ANSI and Unicode.</p>
<p>Oracle started a real Unicode support with Oracle8i but only for bind and fetch data. All SQL and PL/SQ/ statements, database objects names were still only supported in ANSI.</p>
<p>With Oracle 9i, Oracle provides a full Unicode support.</p>
<p>So depending on the compile time Oracle library or the runtime loaded library, Unicode support differs.</p>
<p>OCILIB supports:</p>
<ul>
<li>ANSI (char)</li>
<li>Unicode (wchar_t)</li>
<li>UTF8 strings</li>
</ul>
<p>OCILIB uses the character type 'otext' that is a define around char and wchar_t depending on the charset mode.</p>
<dl class="section user"><dt>Option OCI_CHARSET_ANSI</dt><dd></dd></dl>
<ul>
<li>otext &ndash;&gt; char</li>
<li>OTEXT(x) &ndash;&gt; x</li>
</ul>
<dl class="section user"><dt>Option OCI_CHARSET_WIDE</dt><dd></dd></dl>
<ul>
<li>otext &ndash;&gt; wchar_t</li>
<li>OTEXT(x) &ndash;&gt; L ## x</li>
</ul>
<dl class="section user"><dt>Unicode and ISO C</dt><dd></dd></dl>
<p>Well, ISO C:</p><ul>
<li>doesn't know anything about Unicode.</li>
<li>makes wide characters support tricky because wide character size is not defined and is freely adaptable by implementations.</li>
</ul>
<p>OCILIB uses char/wchar_t strings for both public interface and internal storage.</p>
<p>Unicode builds of OCILIB initialize OCI in UTF16 Unicode mode. Oracle implements this mode with a 2 bytes (fixed length) UTF16 encoding.</p>
<dl class="section warning"><dt>Warning</dt><dd>When using Unicode builds of OCILIB, make sure that the target Database charset is also using an Unicode charset or is a superset of UTF16. If not, strings may be converted with substitution characters by the Oracle client !</dd></dl>
<p>So, on systems implementing wchar_t as 2 bytes based UTF16 (e.g. Ms Windows), strings are directly passed to Oracle and taken back from it.</p>
<p>On other systems (most of the Unix systems) that use UTF32 as encoding, (4 bytes based wchar_t), OCILIB uses:</p><ul>
<li>temporary buffers for statements and object names</li>
<li>buffer expansion from UTF16 to UTF32 for fetch and bind string:<ul>
<li>allocation based on sizeof(wchar_t)</li>
<li>data filling based on sizeof(short) -&gt; (UTF16 2 bytes)</li>
<li>data expansion to sizeof(wchar_t).</li>
</ul>
</li>
</ul>
<p>Buffer expansion is done in place and has the advantage of not requiring extra buffer. That reduces the cost of the Unicode/ISO C handling overhead on Unix systems.</p>
<dl class="section user"><dt>UTF8 strings</dt><dd></dd></dl>
<p>OCILIB fully supports UTF8 strings :</p><ul>
<li>Within OCI_CHARSET_ANSI builds</li>
<li>NLS_LANG environment variable must be set to any valid UTF8 Oracle charset string</li>
</ul>
<dl class="section user"><dt>Charset mapping macros</dt><dd></dd></dl>
<p>OCILIB main header file provides macro around most common string functions of the C standard library.</p>
<p>these macros are based on the model: ostr[libc function name]()</p>
<p>xxx is the standard C library string function name without the character type prefix (str/wcs).</p>
<p>List of available macros:</p><ul>
<li>ostrdup</li>
<li>ostrcpy</li>
<li>ostrncpy</li>
<li>ostrcat</li>
<li>ostrncat</li>
<li>ostrlen</li>
<li>ostrcmp</li>
<li>ostrcasecmp</li>
<li>osprintf</li>
<li>ostol </li>
</ul>
</div><!-- contents -->
</div><!-- doc-content -->
<!-- start footer part -->
<div id="nav-path" class="navpath"><!-- id is needed for treeview function! -->
  <ul>
    <li class="footer">Generated on Mon Mar 21 2016 22:26:36 for OCILIB (C and C++ Driver for Oracle) by
    <a href="http://www.doxygen.org/index.html">
    <img class="footer" src="doxygen.png" alt="doxygen"/></a> 1.8.9.1 </li>
  </ul>
</div>
</body>
</html>
